home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / catman / p_man / cat3 / Benchmark.Z / Benchmark
Encoding:
Text File  |  1998-10-28  |  9.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4.      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))     7777////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.       Benchmark - benchmark    running    times of code
  10.  
  11.       timethis - run a chunk of code several times
  12.  
  13.       timethese - run several chunks of code several times
  14.  
  15.       timeit - run a chunk of code and see how long    it goes
  16.  
  17.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  18.           timethis ($count,    "code");
  19.  
  20.           #    Use Perl code in strings...
  21.           timethese($count,    {
  22.           'Name1' => '...code1...',
  23.           'Name2' => '...code2...',
  24.           });
  25.  
  26.           #    ... or use subroutine references.
  27.           timethese($count,    {
  28.           'Name1' => sub { ...code1... },
  29.           'Name2' => sub { ...code2... },
  30.           });
  31.  
  32.           $t = timeit($count, '...other code...')
  33.           print "$count loops of other code    took:",timestr($t),"\n";
  34.  
  35.  
  36.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.       The Benchmark    module encapsulates a number of    routines to
  38.       help you figure out how long it takes    to execute some    code.
  39.  
  40.       MMMMeeeetttthhhhooooddddssss
  41.  
  42.       new        Returns the    current    time.    Example:
  43.  
  44.             use Benchmark;
  45.             $t0 = new Benchmark;
  46.             # ... your code    here ...
  47.             $t1 = new Benchmark;
  48.             $td = timediff($t1, $t0);
  49.             print "the code    took:",timestr($td),"\n";
  50.  
  51.  
  52.       debug        Enables or disable debugging by setting the
  53.             $Benchmark::Debug flag:
  54.  
  55.             debug Benchmark    1;
  56.             $t = timeit(10,    ' 5 ** $Global ');
  57.             debug Benchmark    0;
  58.  
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                        (printed 10/23/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))     7777////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  71.  
  72.  
  73.  
  74.       SSSSttttaaaannnnddddaaaarrrrdddd EEEExxxxppppoooorrrrttttssss
  75.  
  76.       The following    routines will be exported into your namespace
  77.       if you use the Benchmark module:
  78.  
  79.       timeit(COUNT,    CODE)
  80.             Arguments: COUNT is    the number of times to run the
  81.             loop, and CODE is the code to run.    CODE may be
  82.             either a code reference or a string    to be eval'd;
  83.             either way it will be run in the caller's package.
  84.  
  85.             Returns: a Benchmark object.
  86.  
  87.       timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )
  88.             Time COUNT iterations of CODE. CODE    may be a
  89.             string to eval or a    code reference;    either way the
  90.             CODE will run in the caller's package.  Results
  91.             will be printed to STDOUT as TITLE followed    by the
  92.             times.  TITLE defaults to "timethis    COUNT" if none
  93.             is provided. STYLE determines the format of    the
  94.             output, as described for _t_i_m_e_s_t_r() below.
  95.  
  96.             The    COUNT can be zero or negative: this means the
  97.             _m_i_n_i_m_u_m _n_u_m_b_e_r _o_f _C_P_U _s_e_c_o_n_d_s to run.  A zero
  98.             signifies the default of 3 seconds.     For example
  99.             to run at least for    10 seconds:
  100.  
  101.                 timethis(-10, $code)
  102.  
  103.             or to run two pieces of code tests for at least 3
  104.             seconds:
  105.  
  106.                 timethese(0, { test1 => '...', test2 => '...'})
  107.  
  108.             CPU    seconds    is, in UNIX terms, the user time plus
  109.             the    system time of the process itself, as opposed
  110.             to the real    (wallclock) time and the time spent by
  111.             the    child processes.  Less than 0.1    seconds    is not
  112.             accepted (-0.01 as the count, for example, will
  113.             cause a fatal runtime exception).
  114.  
  115.             Note that the CPU seconds is the mmmmiiiinnnniiiimmmmuuuummmm time: CPU
  116.             scheduling and other operating system factors may
  117.             complicate the attempt so that a little bit    more
  118.             time is spent.  The    benchmark output will,
  119.             however, also tell the number of $code
  120.             runs/second, which should be a more    interesting
  121.             number than    the actually spent seconds.
  122.  
  123.             Returns a Benchmark    object.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                        (printed 10/23/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))     7777////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  137.  
  138.  
  139.  
  140.       timethese ( COUNT, CODEHASHREF, [ STYLE ] )
  141.             The    CODEHASHREF is a reference to a    hash
  142.             containing names as    keys and either    a string to
  143.             eval or a code reference for each value.  For each
  144.             (KEY, VALUE) pair in the CODEHASHREF, this routine
  145.             will call
  146.  
  147.                 timethis(COUNT, VALUE, KEY,    STYLE)
  148.  
  149.             The    routines are called in string comparison order
  150.             of KEY.
  151.  
  152.             The    COUNT can be zero or negative, see _t_i_m_e_t_h_i_s().
  153.  
  154.       timediff ( T1, T2 )
  155.             Returns the    difference between two Benchmark times
  156.             as a Benchmark object suitable for passing to
  157.             _t_i_m_e_s_t_r().
  158.  
  159.       timestr ( TIMEDIFF, [    STYLE, [ FORMAT    ] ] )
  160.             Returns a string that formats the times in the
  161.             TIMEDIFF object in the requested STYLE. TIMEDIFF
  162.             is expected    to be a    Benchmark object similar to
  163.             that returned by _t_i_m_e_d_i_f_f().
  164.  
  165.             STYLE can be any of    'all', 'noc', 'nop' or 'auto'.
  166.             'all' shows    each of    the 5 times available
  167.             ('wallclock' time, user time, system time, user
  168.             time of children, and system time of children).
  169.             'noc' shows    all except the two children times.
  170.             'nop' shows    only wallclock and the two children
  171.             times. 'auto' (the default)    will act as 'all'
  172.             unless the children    times are both zero, in    which
  173.             case it acts as 'noc'.
  174.  
  175.             FORMAT is the the _p_r_i_n_t_f(_3)    manpage-style format
  176.             specifier (without the leading '%')    to use to
  177.             print the times. It    defaults to '5.2f'.
  178.  
  179.       OOOOppppttttiiiioooonnnnaaaallll EEEExxxxppppoooorrrrttttssss
  180.  
  181.       The following    routines will be exported into your namespace
  182.       if you specifically ask that they be imported:
  183.  
  184.       clearcache ( COUNT )
  185.             Clear the cached time for COUNT rounds of the null
  186.             loop.
  187.  
  188.       clearallcache    ( )
  189.             Clear all cached times.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                        (printed 10/23/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))     7777////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  203.  
  204.  
  205.  
  206.       disablecache ( )
  207.             Disable caching of timings for the null loop. This
  208.             will force Benchmark to recalculate    these timings
  209.             for    each new piece of code timed.
  210.  
  211.       enablecache (    )
  212.             Enable caching of timings for the null loop. The
  213.             time taken for COUNT rounds    of the null loop will
  214.             be calculated only once for    each different COUNT
  215.             used.
  216.  
  217.      NNNNOOOOTTTTEEEESSSS
  218.       The data is stored as    a list of values from the time and
  219.       times    functions:
  220.  
  221.         ($real,    $user, $system,    $children_user,    $children_system)
  222.  
  223.       in seconds for the whole loop    (not divided by    the number of
  224.       rounds).
  225.  
  226.       The timing is    done using _t_i_m_e(3) and _t_i_m_e_s(3).
  227.  
  228.       Code is executed in the caller's package.
  229.  
  230.       The time of the null loop (a loop with the same number of
  231.       rounds but empty loop    body) is subtracted from the time of
  232.       the real loop.
  233.  
  234.       The null loop    times are cached, the key being    the number of
  235.       rounds. The caching can be controlled    using calls like
  236.       these:
  237.  
  238.           clearcache($key);
  239.           clearallcache();
  240.  
  241.           disablecache();
  242.           enablecache();
  243.  
  244.  
  245.      IIIINNNNHHHHEEEERRRRIIIITTTTAAAANNNNCCCCEEEE
  246.       Benchmark inherits from no other class, except of course for
  247.       Exporter.
  248.  
  249.      CCCCAAAAVVVVEEEEAAAATTTTSSSS
  250.       Comparing eval'd strings with    code references    will give you
  251.       inaccurate results: a    code reference will show a slower
  252.       execution time than the equivalent eval'd string.
  253.  
  254.       The real time    timing is done using _t_i_m_e(2) and the
  255.       granularity is therefore only    one second.
  256.  
  257.       Short    tests may produce negative figures because perl    can
  258.  
  259.  
  260.  
  261.      Page 4                        (printed 10/23/98)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))     7777////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  269.  
  270.  
  271.  
  272.       appear to take longer    to execute the empty loop than a short
  273.       test;    try:
  274.  
  275.           timethis(100,'1');
  276.  
  277.       The system time of the null loop might be slightly more than
  278.       the system time of the loop with the actual code and
  279.       therefore the    difference might end up    being <    0.
  280.  
  281.      AAAAUUUUTTTTHHHHOOOORRRRSSSS
  282.       Jarkko Hietaniemi <_j_h_i@_i_k_i._f_i>, Tim Bunce
  283.       <_T_i_m._B_u_n_c_e@_i_g._c_o._u_k>
  284.  
  285.      MMMMOOOODDDDIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN HHHHIIIISSSSTTTTOOOORRRRYYYY
  286.       September 8th, 1994; by Tim Bunce.
  287.  
  288.       March    28th, 1997; by Hugo van    der Sanden: added support for
  289.       code references and the already documented 'debug' method;
  290.       revamped documentation.
  291.  
  292.       April    04-07th, 1997: by Jarkko Hietaniemi, added the run-
  293.       for-some-time    functionality.
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.      Page 5                        (printed 10/23/98)
  328.  
  329.  
  330.  
  331.